Getting Started

Following the C-Roads architecture, the concept of an Interchange is implemented in the Mobilidata environment. The interchange is primarly meant as low-latency publish-subscribe service to exchange message with the peripheral functionality.

The message based system is built on an AMQP bus structure, able to exchange almost every type of message, and especially usefull for the small mobility messages used in the Mobilidata environment. The communication is IP based.

Connect to Mobilidata Interchange (MI)

The different steps to be able to connect to the MI are listed below. This flow needs to be followed as it will allow a service to authenticate and be able to subscribe to the AMQP.

Request certificates (+ IP whitelist)

TODO explain how to request certificate + whitelist ip

Create subscription (Local Actor API)

After the certificates are received, a new subscription can be created through the Local Actor API by calling the /subscriptions endpoint with the certificate. The same certificate has to be used in connecting to the AMQP endpoint. More info can be found here. While the subscription is being created the status in the response is REQUESTED. If the subscription is active the response of the GET /subscriptions/<id> endpoint will contain a status of CREATED. In the response there is also more information about endpoint (host and port) of the AMQP endpoint, and with the topic name (source) of the created subscription. The information received can be used to actually subscribe on the correct topic of AMQP.

By default the subscription is valid/active for 15 minutes. After 15 minutes the subscription is removed. To keep the the subscription active the GET /subscriptions/<id> endpoint can be called every 10 minutes. This will refresh the subscription an keep it active.

Example subscription body

POST /subscriptions HTTP/1.1
Host: <hostname>
Content-Type: application/json
{
  "name": "<clientCommonName>",
  "subscriptions": [
    {
      "selector": "<JMS selector>"
    }
  ],
  "version": "<version>"
}

The clientCommonName is the service prodived name received when requesting the certificate. The JSM Selector describes what topics of the AMQP where the subscription be created on. The environment should always be included, eg. dtapEnvironment=acceptance. Different message or protocol types can also be specified. To create a subscription to receive DENM messages (v1.3.1) from acceptance environment this JSM Selector is used: protocolVersion='DENM:1.3.1' AND dtapEnvironment='acceptance'. The version can be obtained by calling the subscriptions endpoint with the clientCommonName. (Current version is 1.1.0)

GET <localActorAPI>/<clientCommonName>/subscriptions HTTP/1.1

JMS Selectors

[TODO list possible JMS selectors for different topics to subscribe on]

Connect to AMQP

With the endpoint information received from the Local Actor API, a connection to AMQP can be established. The connection details are provided by the Local Actor API, together with the earlier requested certificate. The connection string of AMQP will look like amqps://<host>:<port>. The used AMQP library should be able to handle the certificate(s) and the source to connect to the correct topic(s). More info connection to AMQP can be found here.

caution

AMQP version 1.0 is used in the Mobilidata environment.